Bug Proofing Visual Basic: A Guide to Error Handling and Prevention
(Publisher: John Wiley & Sons, Inc.)
Author(s): Rod Stephens
ISBN: 0471323519
Publication Date: 11/01/98

Example File Header

The following example shows a header for a class module. Appendix B, “Header Comment Templates,” contains a blank template for a more complete file header comment. You can download the blank template from the book’s Web page at www.vb-helper.com/err.htm and paste it into your files.

‘ ************************************************

‘ File:         RayRect.CLS
‘ Copyright:    Copyright (c) 1997-1998
‘               Yearlong Filibusters, Inc.
‘ Date Created: 8/20/97
‘ Authors:      Rod Stephens
‘               Michelle Eisgruber
‘               Judy Nishimoto
‘
‘ Purpose:
‘     A ray traced rectangle in 3-D space.
‘
‘ Entry Points:
‘     Sub TraceRay
‘         Follow a ray and see if it hits the
‘         object. Return the point of intersection.
‘
‘     NumEmployees As Integer
‘
‘ Dependencies:
‘     Matrix.BAS   Matrix manipulation functions.
‘
‘ Issues:
‘     Enhancement: Allow transparent surfaces?
‘     Enhancement: Define an inside and outside
‘
‘ Method:
‘     See Visual Basic Graphics Programming,
‘     Chapter 13, for information on ray tracing.
‘ ************************************************
Option Explicit

‘ ************************************************
‘ Global Definitions
‘ --------------------------
‘ Global API Declarations
‘ --------------------------
Public Type POINTAPI
    X As Long
    Y As Long
End Type

Public Declare Function Polygon Lib “gdi32” _
    Alias “Polygon” ( _
    ByVal hdc As Long, lpPoint As POINTAPI, _
    ByVal nCount As Long) As Long

‘--------------------------
‘ Global Types
‘ --------------------------’
Public Type MyType
    Field1 As Integer
    Field2 As Integer
End Type

‘ --------------------------
‘ Global Enums and Constants
‘ --------------------------

Public Enum PayBands
    PayBand_Engineer
    PayBand_Intern
    PayBand_Manager
End Enum

Public Const SUPPORT_PHONE_NUMBER = “867-5309”

‘ --------------------------
‘ Global Variables
‘ --------------------------

Public NumEmployees As Integer

‘ ************************************************
‘Private Definitions
‘ --------------------------
‘ Private API Declarations
‘ --------------------------

Private Const SRCCOPY = &HCC0020

Private Declare Function BitBlt Lib “gdi32” _
    Alias “BitBlt” (ByVal hDestDC As Long,
    ByVal x As Long, ByVal y As Long, _
    ByVal nWidth As Long, ByVal nHeight As Long, _
    ByVal hSrcDC As Long, ByVal xSrc As Long, _
    ByVal ySrc As Long, ByVal dwRop As Long) _
    As Long

‘ --------------------------
‘Private Types
‘ --------------------------

  Private Type MyPrivateType
    Field1 As Integer
End Type

‘ --------------------------
‘ Private Constants and Enums
‘ --------------------------

Private Enum FormColors
    FormColor_Red
    FormColor_Green
    FormColor_Blue
End Enum

Private Const YELLOW_FRUIT = “Banana”

‘ --------------------------
‘
Private Variables
‘ --------------------------

Private NumWorkingEmployees As Byte

Comment Routines

Functions, subroutines, and procedures have a lot in common with files. They, too, should begin with header comments giving important information. This should include a brief explanation of the routine’s purpose. If you cannot describe the purpose in one sentence, it probably does not perform a single, well-defined task. Because that can make the routine harder to understand and debug, you should probably break it into two or more smaller routines that perform well-defined tasks.

If the routine is so complicated that comments within the code do not give enough detail, add a method section that explains the algorithm. Use references to books and articles to keep the explanation brief.

Next, the header should describe the routine’s inputs and outputs. It should explain which variables are modified. These variables should stand out because they are the variables declared ByRef. If the routine is a function or property get procedure, this section should describe the return value. It should also explain any side effects produced by the routine. For example, if the routine modifies a global data structure, it should say so here.

The header comment should then explain any error handling or error generation in the routine. If the code raises an error, the comment should explain when the error is raised and give the error code. The code should be a constant or enumerated value like NETWORK_FILE_NOT_FOUND, not a hard-coded number like 276.

The next section describes any assertions made by the routine. These are verified by the routine and, if an assertion fails, the routine halts. These are different from the errors listed in the previous section. The program can trap errors and continue. When an assertion fails, the routine stops and the program cannot continue.

The header finishes by listing the developers who have worked on the code, the date they made changes, and comments explaining what each developer did.

You may want to leave in sections even if they do not apply to a particular routine. For example, if a function takes no parameters, you may want to use the following comment to make it clear that the input section is blank and not accidentally omitted.

‘Inputs:
‘    None.

The following code shows an example function header. Appendix B, “Header Comment Templates,” contains a blank template for a routine header comment. You can download the blank template from the book’s Web page at www.vb-helper.com/err.htm and paste it into your code.

‘ ************************************************

‘ Purpose: Sort an array of numbers.
‘ Method:  See Ready-to-Run Visual Basic
‘          Algorithms, p.231-232.
‘
‘ Inputs:
‘    numbers   An array of integers to sort.
‘
‘ Outputs:
‘    numbers   The numbers are rearranged so they
‘              are returned sorted.
‘
‘ Errors:
‘    This routine raises no errors.
‘
‘ Asserts:
‘    The number of items in the array is between
‘    10 and 100.
‘
‘    Changed to 10 to 10,000 by Wendy Franklin.
‘
‘ Developer           Date     Comments
‘ ---------           -------- --------
‘ Amy Smith            8/20/97 Initial creation.
‘ Norman Williams     12/21/97 Fixed bug when lower bound < 1.
‘ Wendy Franklin       4/ 3/98 Changed to allow up to 10k items.
‘ ************************************************
Public Sub SelectionSort(ByRef numbers() As Integer)
    :